home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / libraries / bitmap_lib_v13.lha / 3AM / Autodocs / Bitmap.docs
Encoding:
Text File  |  1995-01-09  |  4.6 KB  |  179 lines
  1. /*
  2.  * bitmap.h v1.0
  3.  *
  4.  * Copyright © 1994 by Stefano Reksten of 3AM - The Three Amigos!!!
  5.  * All rights reserved.
  6.  *
  7.  *
  8.  *
  9.  * NAME
  10.  *  CreateBitMap
  11.  *
  12.  * SYNOPSIS
  13.  *  bitmap = CreateBitMap( width, height, depth )
  14.  *
  15.  *  struct BitMap *CreateBitMap( UWORD, UWORD, UBYTE )
  16.  *
  17.  * FUNCTION
  18.  *  This function creates a bitmap of specified width, height and depth.
  19.  *  AllocBitMap from 3.0 will be used if possible (i.e. if you have it!)
  20.  *
  21.  * INPUTS
  22.  *  width, height - two numbers between 0 and 65535
  23.  *  depth - a number between 1 and 8 (for now? :-)
  24.  *
  25.  * RESULTS
  26.  *  a pointer to a BitMap structure ready to be used.
  27.  *
  28.  *
  29.  * NAME
  30.  *  DisposeBitMap
  31.  *
  32.  * SYNOPSIS
  33.  *  DisposeBitMap( bitmap )
  34.  *
  35.  *  void DisposeBitMap( struct BitMap * )
  36.  *
  37.  * FUNCTION
  38.  *  Deallocates a BitMap structure freeing each plane and the
  39.  *  structure itself.
  40.  *
  41.  * INPUTS
  42.  *  bitmap - a pointer to an usable BitMap structure
  43.  *
  44.  * RESULTS
  45.  *
  46.  *
  47.  *
  48.  * NAME
  49.  *  ScaleBitMap
  50.  *
  51.  * SYNOPSIS
  52.  *  success = ScaleBitMap( scaleInfo )
  53.  *
  54.  *  BOOL = ScaleBitMap( struct BitMapScaleInfo* )
  55.  *
  56.  * FUNCTION
  57.  *  This function scales a bitmap. There is a function in kickstart 2.0+
  58.  *  that does a similar trick but is slower, not 1.3 compatible,  can't
  59.  *  invert horizontally or vertically the bitmap, source and destination
  60.  *  may not overlap.
  61.  *  To use this function you should ready a struct BitMapScaleInfo. For a
  62.  *  complete description of this structure, see "libraries/bitmap.h".
  63.  *
  64.  * INPUTS
  65.  *  a pointer to an initialized struct BitMapScaleInfo
  66.  *
  67.  * RESULTS
  68.  *  a scaled BitMap
  69.  *
  70.  *
  71.  *
  72.  *
  73.  * NAME
  74.  *  CreateCTPTable
  75.  *
  76.  * SYNOPSIS
  77.  *  table = CreateCTPTable( bitmap )
  78.  *
  79.  *  ULONG * = CreateCTPTable( struct BitMap * )
  80.  *
  81.  * FUNCTION
  82.  *  This function allocates and fills with proper data a table to be
  83.  *  used with any of the ChunkyToPlanar functions described below.
  84.  *  Make sure you get a table before calling them!
  85.  *  For each bitmap you want to use the latter functions on, you
  86.  *  need one of these tables.
  87.  *
  88.  * INPUT
  89.  *  a pointer to a valid BitMap structure.
  90.  *
  91.  * RESULTS
  92.  *  a pointer to a table of ULONGS (you don't need to fully understand
  93.  *  how it works, just make sure it exists)
  94.  *
  95.  *
  96.  *
  97.  *
  98.  * NAME
  99.  *  FreeCTPTable
  100.  *
  101.  * SYNOPSIS
  102.  *  FreeCTPTable( table, bitmap )
  103.  *
  104.  *  void FreeCTPTable( ULONG *, struct BitMap * )
  105.  *
  106.  * FUNCTION
  107.  *  Frees a table obtained from CreateCTPTable
  108.  *
  109.  * INPUTS the pointer returned by CreateCTPTable
  110.  *
  111.  * SEE ALSO
  112.  *  CreateCTPTable(), any ChunkyToPlanar...() function
  113.  *
  114.  *
  115.  *
  116.  * NAME
  117.  *  ChunkyToPlanar
  118.  *  ChunkyToPlanar68020
  119.  *
  120.  * SYNOPSIS
  121.  *  ChunkyToPlanar( bitmap, coord_x, coord_y, color, table )
  122.  *  ChunkyToPlanar68020( bitmap, coord_x, coord_y, color, table )
  123.  *
  124.  *  void ChunkyToPlanar( struct BitMap *, UWORD, UWORD, UBYTE, ULONG * )
  125.  *  void ChunkyToPlanar68020( struct BitMap *, UWORD, UWORD, UBYTE, ULONG * )
  126.  *
  127.  * FUNCTION
  128.  *  Writes a Chunky Pixel to a bitmap. WARNING: to gain speed this
  129.  *  function DOES NOT MAKE ANY CONTROL on the bitmap it writes on.
  130.  *  But at least is nearly twice times faster than WritePixel.
  131.  *  68020 version is even faster (but, if you don't have a 68020 or
  132.  *  upper, don't use it): more than twice times WritePixel.
  133.  *
  134.  * INPUTS
  135.  *  bitmap: a pointer to a valid BitMap structure
  136.  *  coord_x, coord_y: the coordinates of the point to be written
  137.  *  color: a valid pen number
  138.  *  table: a table of ULONGS returned by CreateCTPTable (having passed
  139.  *         the *SAME* bitmap)
  140.  *
  141.  * SEE ALSO
  142.  *  CreateCTPTable(), ChunkyToPlanarArray68020()
  143.  *
  144.  *
  145.  *
  146.  *
  147.  * NAME
  148.  *  ChunkyToPlanarArray68020
  149.  *
  150.  * SYNOPSIS
  151.  *  ChunkyToPlanarArray68020( bitmap, coord_x, coord_y, array,
  152.  *                            table, width, height, arrays_pixelsPerRow )
  153.  *
  154.  *  void ChunkyToPlanar68020( struct BitMap *, UWORD, UWORD, UBYTE *,
  155.  *                            ULONG *, UWORD, UWORD, UWORD )
  156.  *
  157.  * FUNCTION
  158.  *  Writes an array of chunky pixels in a bitmap, specifying starting
  159.  *  coordinates and dimensions. WARNING: to gain speed NO CONTROL is
  160.  *  made. But at least, this function is fast.
  161.  *
  162.  * INPUTS
  163.  *  bitmap: a pointer to a valid BitMap structure
  164.  *  coord_x, coord_y: coordinates of starting point in bitmap
  165.  *  table: a table of ULONGS returned by CreateCTPTable (having passed
  166.  *         the *SAME* bitmap)
  167.  *  array: an array of pen colors
  168.  *  width, height: how many pixels will be affected.
  169.  *  arrays_pixelsPerRow: how many pixels does a single row contain.
  170.  *
  171.  * BUGS:
  172.  *  This function is (by now) for 68020 only (due to speed reasons).
  173.  *  Starting point in the array of colors can't be specified. But it
  174.  *  can anyway be choosen by passing (array + x * arrays_pixelsPerRow + y)
  175.  *  where x and y are the coordinates of the starting point instead of
  176.  *  (array).
  177.  *
  178.  */
  179.